home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / public / GNU / emacs.inst / emacs19.idb / usr / gnu / info / elisp-12.z / elisp-12
Encoding:
GNU Info File  |  1994-08-02  |  50.1 KB  |  1,289 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.  
  4.    This version is newer than the second printed edition of the GNU
  5. Emacs Lisp Reference Manual.  It corresponds to Emacs Version 19.19.
  6.  
  7.    Published by the Free Software Foundation 675 Massachusetts Avenue
  8. Cambridge, MA 02139 USA
  9.  
  10.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26.    Permission is granted to copy and distribute modified versions of
  27. this manual under the conditions for verbatim copying, provided also
  28. that the section entitled "GNU Emacs General Public License" is included
  29. exactly as in the original, and provided that the entire resulting
  30. derived work is distributed under the terms of a permission notice
  31. identical to this one.
  32.  
  33.    Permission is granted to copy and distribute translations of this
  34. manual into another language, under the above conditions for modified
  35. versions, except that the section entitled "GNU Emacs General Public
  36. License" may be included in a translation approved by the Free Software
  37. Foundation instead of in the original English.
  38.  
  39. 
  40. File: elisp,  Node: Output Streams,  Next: Output Functions,  Prev: Input Functions,  Up: Streams
  41.  
  42. Output Streams
  43. ==============
  44.  
  45.    An output stream specifies what to do with the characters produced
  46. by printing.  Most print functions accept an output stream as an
  47. optional argument.  Here are the possible types of output stream:
  48.  
  49. BUFFER
  50.      The output characters are inserted into BUFFER at point.  Point
  51.      advances as characters are inserted.
  52.  
  53. MARKER
  54.      The output characters are inserted into the buffer that MARKER is
  55.      in at the marker position.  The position advances as characters are
  56.      inserted.  The value of point in the buffer has no effect when the
  57.      stream is a marker.
  58.  
  59. FUNCTION
  60.      The output characters are passed to FUNCTION, which is responsible
  61.      for storing them away.  It is called with a single character as
  62.      argument, as many times as there are characters to be output, and
  63.      is free to do anything at all with the characters it receives.
  64.  
  65. `t'
  66.      The output characters are displayed in the echo area.
  67.  
  68. `nil'
  69.      `nil' specified as an output stream means that the value of
  70.      `standard-output' should be used as the output stream; that value
  71.      is the "default output stream", and must be a non-`nil' output
  72.      stream.
  73.  
  74. SYMBOL
  75.      A symbol as output stream is equivalent to the symbol's function
  76.      definition (if any).
  77.  
  78.    Here is an example of a buffer used as an output stream.  Point is
  79. initially located as shown immediately before the `h' in `the'.  At the
  80. end, point is located directly before that same `h'.
  81.  
  82.      ---------- Buffer: foo ----------
  83.      This is t-!-he contents of foo.
  84.      ---------- Buffer: foo ----------
  85.      
  86.      (print "This is the output" (get-buffer "foo"))
  87.           => "This is the output"
  88.      
  89.      ---------- Buffer: foo ----------
  90.      This is t
  91.      "This is the output"
  92.      -!-he contents of foo.
  93.      ---------- Buffer: foo ----------
  94.  
  95.    Now we show a use of a marker as an output stream.  Initially, the
  96. marker points in buffer `foo', between the `t' and the `h' in the word
  97. `the'.  At the end, the marker has been advanced over the inserted text
  98. so that it still points before the same `h'.  Note that the location of
  99. point, shown in the usual fashion, has no effect.
  100.  
  101.      ---------- Buffer: foo ----------
  102.      "This is the -!-output"
  103.      ---------- Buffer: foo ----------
  104.      
  105.      m
  106.           => #<marker at 11 in foo>
  107.      
  108.      (print "More output for foo." m)
  109.           => "More output for foo."
  110.      
  111.      ---------- Buffer: foo ----------
  112.      "This is t
  113.      "More output for foo."
  114.      he -!-output"
  115.      ---------- Buffer: foo ----------
  116.      
  117.      m
  118.           => #<marker at 35 in foo>
  119.  
  120.    The following example shows output to the echo area:
  121.  
  122.      (print "Echo Area output" t)
  123.           => "Echo Area output"
  124.      ---------- Echo Area ----------
  125.      "Echo Area output"
  126.      ---------- Echo Area ----------
  127.  
  128.    Finally, we show an output stream which is a function.  The function
  129. `eat-output' takes each character that it is given and conses it onto
  130. the front of the list `last-output' (*note Building Lists::.).  At the
  131. end, the list contains all the characters output, but in reverse order.
  132.  
  133.      (setq last-output nil)
  134.           => nil
  135.      
  136.      (defun eat-output (c)
  137.        (setq last-output (cons c last-output)))
  138.           => eat-output
  139.      
  140.      (print "This is the output" 'eat-output)
  141.           => "This is the output"
  142.      
  143.      last-output
  144.           => (10 34 116 117 112 116 117 111 32 101 104
  145.          116 32 115 105 32 115 105 104 84 34 10)
  146.  
  147. Now we can put the output in the proper order by reversing the list:
  148.  
  149.      (concat (nreverse last-output))
  150.           => "
  151.      \"This is the output\"
  152.      "
  153.  
  154. 
  155. File: elisp,  Node: Output Functions,  Next: Output Variables,  Prev: Output Streams,  Up: Streams
  156.  
  157. Output Functions
  158. ================
  159.  
  160.    This section describes the Lisp functions for printing Lisp objects.
  161.  
  162.    Some of the Emacs printing functions add quoting characters to the
  163. output when necessary so that it can be read properly.  The quoting
  164. characters used are `\' and `"'; they are used to distinguish strings
  165. from symbols, and to prevent punctuation characters in strings and
  166. symbols from being taken as delimiters.  *Note Printed
  167. Representation::, for full details.  You specify quoting or no quoting
  168. by the choice of printing function.
  169.  
  170.    If the text is to be read back into Lisp, then it is best to print
  171. with quoting characters to avoid ambiguity.  Likewise, if the purpose is
  172. to describe a Lisp object clearly for a Lisp programmer.  However, if
  173. the purpose of the output is to look nice for humans, then it is better
  174. to print without quoting.
  175.  
  176.    Printing a self-referent Lisp object requires an infinite amount of
  177. text.  In certain cases, trying to produce this text leads to a stack
  178. overflow.  Emacs detects such recursion and prints `#LEVEL' instead of
  179. recursively printing an object already being printed.  For example,
  180. here `#0' indicates a recursive reference to the object at level 0 of
  181. the current print operation:
  182.  
  183.      (setq foo (list nil))
  184.           => (nil)
  185.      (setcar foo foo)
  186.           => (#0)
  187.  
  188.    In the functions below, STREAM stands for an output stream.  (See
  189. the previous section for a description of output streams.)  If STREAM
  190. is `nil' or omitted, it defaults to the value of `standard-output'.
  191.  
  192.  - Function: print OBJECT &optional STREAM
  193.      The `print' is a convenient way of printing.  It outputs the
  194.      printed representation of OBJECT to STREAM, printing in addition
  195.      one newline before OBJECT and another after it.  Quoting
  196.      characters are used.  `print' returns OBJECT.  For example:
  197.  
  198.           (progn (print 'The\ cat\ in)
  199.                  (print "the hat")
  200.                  (print " came back"))
  201.                -|
  202.                -| The\ cat\ in
  203.                -|
  204.                -| "the hat"
  205.                -|
  206.                -| " came back"
  207.                -|
  208.                => " came back"
  209.  
  210.  - Function: prin1 OBJECT &optional STREAM
  211.      This function outputs the printed representation of OBJECT to
  212.      STREAM.  It does not print any spaces or newlines to separate
  213.      output as `print' does, but it does use quoting characters just
  214.      like `print'.  It returns OBJECT.
  215.  
  216.           (progn (prin1 'The\ cat\ in)
  217.                  (prin1 "the hat")
  218.                  (prin1 " came back"))
  219.                -| The\ cat\ in"the hat"" came back"
  220.                => " came back"
  221.  
  222.  - Function: princ OBJECT &optional STREAM
  223.      This function outputs the printed representation of OBJECT to
  224.      STREAM.  It returns OBJECT.
  225.  
  226.      This function is intended to produce output that is readable by
  227.      people, not by `read', so quoting characters are not used and
  228.      double-quotes are not printed around the contents of strings.  It
  229.      does not add any spacing between calls.
  230.  
  231.           (progn
  232.             (princ 'The\ cat)
  233.             (princ " in the \"hat\""))
  234.                -| The cat in the "hat"
  235.                => " in the \"hat\""
  236.  
  237.  - Function: terpri &optional STREAM
  238.      This function outputs a newline to STREAM.  The name stands for
  239.      "terminate print".
  240.  
  241.  - Function: write-char CHARACTER &optional STREAM
  242.      This function outputs CHARACTER to STREAM.  It returns CHARACTER.
  243.  
  244.  - Function: prin1-to-string OBJECT &optional NOESCAPE
  245.      This function returns a string containing the text that `prin1'
  246.      would have printed for the same argument.
  247.  
  248.           (prin1-to-string 'foo)
  249.                => "foo"
  250.           (prin1-to-string (mark-marker))
  251.                => "#<marker at 2773 in strings.texi>"
  252.  
  253.      If NOESCAPE is non-`nil', that inhibits use of quoting characters
  254.      in the output.  (This argument is supported in Emacs versions 19
  255.      and later.)
  256.  
  257.           (prin1-to-string "foo")
  258.                => "\"foo\""
  259.           (prin1-to-string "foo" t)
  260.                => "foo"
  261.  
  262.      See `format', in *Note String Conversion::, for other ways to
  263.      obtain the printed representation of a Lisp object as a string.
  264.  
  265. 
  266. File: elisp,  Node: Output Variables,  Prev: Output Functions,  Up: Streams
  267.  
  268. Variables Affecting Output
  269. ==========================
  270.  
  271.  - Variable: standard-output
  272.      The value of this variable is the default output stream, used when
  273.      the STREAM argument is omitted or `nil'.
  274.  
  275.  - Variable: print-escape-newlines
  276.      If this variable is non-`nil', then newline characters in strings
  277.      are printed as `\n'.  Normally they are printed as actual newlines.
  278.  
  279.      This variable affects the print functions `prin1' and `print', as
  280.      well as everything that uses them.  It does not affect `princ'.
  281.      Here is an example using `prin1':
  282.  
  283.           (prin1 "a\nb")
  284.                -| "a
  285.                -| b"
  286.                => "a
  287.                => b"
  288.           
  289.           (let ((print-escape-newlines t))
  290.             (prin1 "a\nb"))
  291.                -| "a\nb"
  292.                => "a
  293.                => b"
  294.  
  295.      In the second expression, the local binding of
  296.      `print-escape-newlines' is in effect during the call to `prin1',
  297.      but not during the printing of the result.
  298.  
  299.  - Variable: print-length
  300.      The value of this variable is the maximum number of elements of a
  301.      list that will be printed.  If the list being printed has more
  302.      than this many elements, then it is abbreviated with an ellipsis.
  303.  
  304.      If the value is `nil' (the default), then there is no limit.
  305.  
  306.           (setq print-length 2)
  307.                => 2
  308.           (print '(1 2 3 4 5))
  309.                -| (1 2 ...)
  310.                => (1 2 ...)
  311.  
  312.  - Variable: print-level
  313.      The value of this variable is the maximum depth of nesting of
  314.      parentheses that will be printed.  Any list or vector at a depth
  315.      exceeding this limit is abbreviated with an ellipsis.  A value of
  316.      `nil' (which is the default) means no limit.
  317.  
  318.      This variable exists in version 19 and later versions.
  319.  
  320. 
  321. File: elisp,  Node: Minibuffers,  Next: Command Loop,  Prev: Streams,  Up: Top
  322.  
  323. Minibuffers
  324. ***********
  325.  
  326.    A "minibuffer" is a special buffer that Emacs commands use to read
  327. arguments more complicated than the single numeric prefix argument.
  328. These arguments include file names, buffer names, and command names (as
  329. in `M-x').  The minibuffer is displayed on the bottom line of the
  330. screen, in the same place as the echo area, but only while it is in use
  331. for reading an argument.
  332.  
  333. * Menu:
  334.  
  335. * Intro to Minibuffers::      Basic information about minibuffers.
  336. * Text from Minibuffer::      How to read a straight text string.
  337. * Object from Minibuffer::    How to read a Lisp object or expression.
  338. * Minibuffer History::          Recording previous minibuffer inputs
  339.                 so the user can reuse them.
  340. * Completion::                How to invoke and customize completion.
  341. * Yes-or-No Queries::         Asking a question with a simple answer.
  342. * Multiple Queries::          Asking a series of similar questions.
  343. * Minibuffer Misc::           Various customization hooks and variables.
  344.  
  345. 
  346. File: elisp,  Node: Intro to Minibuffers,  Next: Text from Minibuffer,  Up: Minibuffers
  347.  
  348. Introduction to Minibuffers
  349. ===========================
  350.  
  351.    In most ways, a minibuffer is a normal Emacs buffer.  Most operations
  352. *within* a buffer, such as editing commands, work normally in a
  353. minibuffer.  However, many operations for managing buffers do not apply
  354. to minibuffers.  The name of a minibuffer always has the form
  355. ` *Minibuf-NUMBER', and it cannot be changed.  Minibuffers are
  356. displayed only in special windows used only for minibuffers; these
  357. windows always appear at the bottom of a frame.  (Sometime frames have
  358. no minibuffer window, and sometimes a special kind of frame contains
  359. nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
  360.  
  361.    The minibuffers window is normally a single line; you can resize it
  362. temporarily with the window sizing commands, but reverts to its normal
  363. size when the minibuffer is exited.
  364.  
  365.    A "recursive minibuffer" may be created when there is an active
  366. minibuffer and a command is invoked that requires input from a
  367. minibuffer.  The first minibuffer is named ` *Minibuf-0*'.  Recursive
  368. minibuffers are named by incrementing the number at the end of the
  369. name.  (The names begin with a space so that they won't show up in
  370. normal buffer lists.)  Of several recursive minibuffers, the innermost
  371. (or most recently entered) is the active minibuffer.  We usually call
  372. this "the" minibuffer.  You can permit or forbid recursive minibuffers
  373. by setting the variable `enable-recursive-minibuffers' or by putting
  374. properties of that name on command symbols (*note Minibuffer Misc::.).
  375.  
  376.    Like other buffers, a minibuffer may use any of several local keymaps
  377. (*note Keymaps::.); these contain various exit commands and in some
  378. cases completion commands.  *Note Completion::.
  379.  
  380.    * `minibuffer-local-map' is for ordinary input (no completion).
  381.  
  382.    * `minibuffer-local-ns-map' is similar, except that SPC exits just
  383.      like RET.  This is used mainly for Mocklisp compatibility.
  384.  
  385.    * `minibuffer-local-completion-map' is for permissive completion.
  386.  
  387.    * `minibuffer-local-must-match-map' is for strict completion and for
  388.      cautious completion.
  389.  
  390. 
  391. File: elisp,  Node: Text from Minibuffer,  Next: Object from Minibuffer,  Prev: Intro to Minibuffers,  Up: Minibuffers
  392.  
  393. Reading Text Strings with the Minibuffer
  394. ========================================
  395.  
  396.    The minibuffer is usually used to read text which is returned as a
  397. string, but can also be used to read a Lisp object in textual form.  The
  398. most basic primitive for minibuffer input is `read-from-minibuffer'.
  399.  
  400.  - Function: read-from-minibuffer PROMPT-STRING &optional INITIAL
  401.           KEYMAP READ HIST
  402.      This function is the most general way to get input through the
  403.      minibuffer.  By default, it accepts arbitrary text and returns it
  404.      as a string; however, if READ is non-`nil', then it uses `read' to
  405.      convert the text into a Lisp object (*note Input Functions::.).
  406.  
  407.      The first thing this function does is to activate a minibuffer and
  408.      display it with PROMPT-STRING as the prompt.  This value must be a
  409.      string.
  410.  
  411.      Then, if INITIAL is a string; its contents are inserted into the
  412.      minibuffer as initial contents.  The text thus inserted is treated
  413.      as if the user had inserted it; the user can alter it with Emacs
  414.      editing commands.
  415.  
  416.      The value of INITIAL may also be a cons cell of the form `(STRING
  417.      . POSITION)'.  This means to insert STRING in the minibuffer but
  418.      put the cursor POSITION characters from the beginning, rather than
  419.      at the end.
  420.  
  421.      If KEYMAP is non-`nil', that keymap is the local keymap to use
  422.      while reading.  If KEYMAP is omitted or `nil', the value of
  423.      `minibuffer-local-map' is used as the keymap.  Specifying a keymap
  424.      is the most important way to customize minibuffer input for
  425.      various applications including completion.
  426.  
  427.      The argument HIST specifies which history list variable to use for
  428.      saving the input and for history commands used in the minibuffer.
  429.      It defaults to `minibuffer-history'.  *Note Minibuffer History::.
  430.  
  431.      When the user types a command to exit the minibuffer, the current
  432.      minibuffer contents are usually made into a string which becomes
  433.      the value of `read-from-minibuffer'.  However, if READ is
  434.      non-`nil', `read-from-minibuffer' converts the result to a Lisp
  435.      object, and returns that object, unevaluated.
  436.  
  437.      Suppose, for example, you are writing a search command and want to
  438.      record the last search string and provide it as a default for the
  439.      next search.  Suppose that the previous search string is stored in
  440.      the variable `last-search-string'.  Here is how you can read a
  441.      search string while providing the previous string as initial input
  442.      to be edited:
  443.  
  444.           (read-from-minibuffer "Find string: " last-search-string)
  445.  
  446.      Assuming the value of `last-search-string' is `No', and the user
  447.      wants to search for `Nope', the interaction looks like this:
  448.  
  449.           (setq last-search-string "No")
  450.           
  451.           (read-from-minibuffer "Find string: " last-search-string)
  452.           ---------- Buffer: Minibuffer ----------
  453.           Find string: No-!-
  454.           ---------- Buffer: Minibuffer ----------
  455.           ;; The user now types `pe RET':
  456.                => "Nope"
  457.  
  458.      This technique is no longer preferred for most applications; it is
  459.      usually better to use a history list.
  460.  
  461.  - Function: read-string PROMPT &optional INITIAL
  462.      This function reads a string from the minibuffer and returns it.
  463.      The arguments PROMPT and INITIAL are used as in
  464.      `read-from-minibuffer'.
  465.  
  466.      This is a simplified interface to the `read-from-minibuffer'
  467.      function:
  468.  
  469.           (read-string PROMPT INITIAL)
  470.           ==
  471.           (read-from-minibuffer PROMPT INITIAL nil nil)
  472.  
  473.  - Variable: minibuffer-local-map
  474.      This is the default local keymap for reading from the minibuffer.
  475.      It is the keymap used by the minibuffer for local bindings in the
  476.      function `read-string'.  By default, it makes the following
  477.      bindings:
  478.  
  479.     LFD
  480.           `exit-minibuffer'
  481.  
  482.     RET
  483.           `exit-minibuffer'
  484.  
  485.     `C-g'
  486.           `abort-recursive-edit'
  487.  
  488.     `M-n' and `M-p'
  489.           `next-history-element' and `previous-history-element'
  490.  
  491.     `M-r'
  492.           `next-matching-history-element'
  493.  
  494.     `M-s'
  495.           `previous-matching-history-element'
  496.  
  497.  - Function: read-no-blanks-input PROMPT &optional INITIAL
  498.      This function reads a string from the minibuffer, but does not
  499.      allow whitespace characters as part of the input: instead, those
  500.      characters terminate the input.  The arguments PROMPT and INITIAL
  501.      are used as in `read-from-minibuffer'.
  502.  
  503.      This is a simplified interface to the `read-from-minibuffer'
  504.      function, and passes the value of the `minibuffer-local-ns-map'
  505.      keymap as the KEYMAP argument for that function.  Since the keymap
  506.      `minibuffer-local-ns-map' does not rebind `C-q', it *is* possible
  507.      to put a space into the string, by quoting it.
  508.  
  509.           (read-no-blanks-input PROMPT INITIAL)
  510.           ==
  511.           (read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map)
  512.  
  513.  - Variable: minibuffer-local-ns-map
  514.      This built-in variable is the keymap used as the minibuffer local
  515.      keymap in the function `read-no-blanks-input'.  By default, it
  516.      makes the following bindings:
  517.  
  518.     LFD
  519.           `exit-minibuffer'
  520.  
  521.     SPC
  522.           `exit-minibuffer'
  523.  
  524.     TAB
  525.           `exit-minibuffer'
  526.  
  527.     RET
  528.           `exit-minibuffer'
  529.  
  530.     `C-g'
  531.           `abort-recursive-edit'
  532.  
  533.     `?'
  534.           `self-insert-and-exit'
  535.  
  536.     `M-n' and `M-p'
  537.           `next-history-element' and `previous-history-element'
  538.  
  539.     `M-r'
  540.           `next-matching-history-element'
  541.  
  542.     `M-s'
  543.           `previous-matching-history-element'
  544.  
  545. 
  546. File: elisp,  Node: Object from Minibuffer,  Next: Minibuffer History,  Prev: Text from Minibuffer,  Up: Minibuffers
  547.  
  548. Reading Lisp Objects with the Minibuffer
  549. ========================================
  550.  
  551.    This section describes functions for reading Lisp objects with the
  552. minibuffer.
  553.  
  554.  - Function: read-minibuffer PROMPT &optional INITIAL
  555.      This function reads a Lisp object in the minibuffer and returns it,
  556.      without evaluating it.  The arguments PROMPT and INITIAL are used
  557.      as in `read-from-minibuffer'; in particular, INITIAL must be a
  558.      string or `nil'.
  559.  
  560.      This is a simplified interface to the `read-from-minibuffer'
  561.      function:
  562.  
  563.           (read-minibuffer PROMPT INITIAL)
  564.           ==
  565.           (read-from-minibuffer PROMPT INITIAL nil t)
  566.  
  567.      Here is an example in which we supply the string `"(testing)"' as
  568.      initial input:
  569.  
  570.           (read-minibuffer
  571.            "Enter an expression: " (format "%s" '(testing)))
  572.           
  573.           ;; Here is how the minibuffer is displayed:
  574.  
  575.           ---------- Buffer: Minibuffer ----------
  576.           Enter an expression: (testing)-!-
  577.           ---------- Buffer: Minibuffer ----------
  578.  
  579.      The user can type RET immediately to use the initial input as a
  580.      default, or can edit the input.
  581.  
  582.  - Function: eval-minibuffer PROMPT &optional INITIAL
  583.      This function reads a Lisp expression in the minibuffer, evaluates
  584.      it, then returns the result.  The arguments PROMPT and INITIAL are
  585.      used as in `read-from-minibuffer'.
  586.  
  587.      This function simply evaluates the result of a call to
  588.      `read-minibuffer':
  589.  
  590.           (eval-minibuffer PROMPT INITIAL)
  591.           ==
  592.           (eval (read-minibuffer PROMPT INITIAL))
  593.  
  594.  - Function: edit-and-eval-command PROMPT FORM
  595.      This function reads a Lisp expression in the minibuffer, and then
  596.      evaluates it.  The difference between this command and
  597.      `eval-minibuffer' is that here the initial FORM is not optional
  598.      and it is treated as a Lisp object to be converted to printed
  599.      representation rather than as a string of text.  It is printed with
  600.      `prin1', so if it is a string, double-quote characters (`"')
  601.      appear in the initial text.  *Note Output Functions::.
  602.  
  603.      The first thing `edit-and-eval-command' does is to activate the
  604.      minibuffer with PROMPT as the prompt.  Then it inserts the printed
  605.      representation of FORM in the minibuffer, and lets the user edit.
  606.      When the user exits the minibuffer, the edited text is read with
  607.      `read' and then evaluated.  The resulting value becomes the value
  608.      of `edit-and-eval-command'.
  609.  
  610.      In the following example, we offer the user an expression with
  611.      initial text which is a valid form already:
  612.  
  613.           (edit-and-eval-command "Please edit: " '(forward-word 1))
  614.           
  615.           ;; After evaluating the preceding expression,
  616.           ;;   the following appears in the minibuffer:
  617.  
  618.           ---------- Buffer: Minibuffer ----------
  619.           Please edit: (forward-word 1)-!-
  620.           ---------- Buffer: Minibuffer ----------
  621.  
  622.      Typing RET right away would exit the minibuffer and evaluate the
  623.      expression, thus moving point forward one word.
  624.      `edit-and-eval-command' returns `nil' in this example.
  625.  
  626. 
  627. File: elisp,  Node: Minibuffer History,  Next: Completion,  Prev: Object from Minibuffer,  Up: Minibuffers
  628.  
  629. Minibuffer History
  630. ==================
  631.  
  632.    A minibuffer history list records previous minibuffer inputs so the
  633. user can reuse them conveniently.  There are many separate history lists
  634. which contain different kinds of inputs.  The Lisp programmer's job is
  635. to specify the right history list for each use of the minibuffer.
  636.  
  637.    The basic minibuffer input functions `read-from-minibuffer' and
  638. `completing-read' both accept an optional argument named HIST which is
  639. how you specify the history list.  Here are the possible values:
  640.  
  641. VARIABLE
  642.      If you specify a variable (a symbol), that variable is the history
  643.      list.
  644.  
  645. (VARIABLE . STARTPOS)
  646.      If you specify a cons cell of this form, then VARIABLE is the
  647.      history list variable, and STARTPOS specifies the initial history
  648.      position (an integer, counting from zero which specifies the most
  649.      recent element of the history).
  650.  
  651.      If you specify STARTPOS, then you should also specify that element
  652.      of the history as INITIAL, for consistency.
  653.  
  654.    If you don't specify HIST, then the default history list
  655. `minibuffer-history' is used.  For other standard history lists, see
  656. below.  You can also create your own history list variable; just
  657. initialize it to `nil' before the first use.  The value of the history
  658. list variable is a list of strings, most recent first.
  659.  
  660.    Both `read-from-minibuffer' and `completing-read' add new elements
  661. to the history list automatically, and provide commands to allow the
  662. user to reuse items on the list.  The only thing your program needs to
  663. do to use a history list is to initialize it and to pass its name to
  664. the input functions when you wish.  But it is safe to modify the list
  665. by hand when the minibuffer input functions are not using it.
  666.  
  667.  - Variable: minibuffer-history
  668.      The default history list for minibuffer history input.
  669.  
  670.  - Variable: query-replace-history
  671.      A history list for arguments to `query-replace' (and similar
  672.      arguments to other commands).
  673.  
  674.  - Variable: file-name-history
  675.      A history list for file name arguments.
  676.  
  677. 
  678. File: elisp,  Node: Completion,  Next: Yes-or-No Queries,  Prev: Minibuffer History,  Up: Minibuffers
  679.  
  680. Completion
  681. ==========
  682.  
  683.    "Completion" is a feature that fills in the rest of a name starting
  684. from an abbreviation for it.  Completion works by comparing the user's
  685. input against a list of valid names and determining how much of the
  686. name is determined uniquely by what the user has typed.
  687.  
  688.    For example, when you type `C-x b' (`switch-to-buffer') and then
  689. type the first few letters of the name of the buffer to which you wish
  690. to switch, and then type TAB (`minibuffer-complete'), Emacs extends the
  691. name as far as it can.  Standard Emacs commands offer completion for
  692. names of symbols, files, buffers, and processes; with the functions in
  693. this section, you can implement completion for other kinds of names.
  694.  
  695.    The `try-completion' function is the basic primitive for completion:
  696. it returns the longest determined completion of a given initial string,
  697. with a given set of strings to match against.
  698.  
  699.    The function `completing-read' provides a higher-level interface for
  700. completion.  A call to `completing-read' specifies how to determine the
  701. list of valid names.  The function then activates the minibuffer with a
  702. local keymap that binds a few keys to commands useful for completion.
  703. Other functions provide convenient simple interfaces for reading
  704. certain kinds of names with completion.
  705.  
  706. * Menu:
  707.  
  708. * Basic Completion::       Low-level functions for completing strings.
  709.                              (These are too low level to use the minibuffer.)
  710. * Programmed Completion::  Finding the completions for a given file name.
  711. * Minibuffer Completion::  Invoking the minibuffer with completion.
  712. * Completion Commands::    Minibuffer commands that do completion.
  713. * High-Level Completion::  Convenient special cases of completion
  714.                              (reading buffer name, file name, etc.)
  715. * Reading File Names::     Using completion to read file names.
  716. * Lisp Symbol Completion:: Completing the name of a symbol.
  717.  
  718. 
  719. File: elisp,  Node: Basic Completion,  Next: Programmed Completion,  Up: Completion
  720.  
  721. Basic Completion Functions
  722. --------------------------
  723.  
  724.  - Function: try-completion STRING COLLECTION &optional PREDICATE
  725.      This function returns the longest common substring of all possible
  726.      completions of STRING in COLLECTION.  The value of COLLECTION must
  727.      be an alist, an obarray, or a function which implements a virtual
  728.      set of strings.
  729.  
  730.      If COLLECTION is an alist (*note Association Lists::.), completion
  731.      compares the CAR of each cons cell in it against STRING; if the
  732.      beginning of the CAR equals STRING, the cons cell matches.  If no
  733.      cons cells match, `try-completion' returns `nil'.  If only one
  734.      cons cell matches, and the match is exact, then `try-completion'
  735.      returns `t'.  Otherwise, the value is the longest initial sequence
  736.      common to all the matching strings in the alist.
  737.  
  738.      If COLLECTION is an obarray (*note Creating Symbols::.), the names
  739.      of all symbols in the obarray form the space of possible
  740.      completions.  They are tested and used just like the CARs of the
  741.      elements of an association list.  (The global variable `obarray'
  742.      holds an obarray containing the names of all interned Lisp
  743.      symbols.)
  744.  
  745.      Note that the only valid way to make a new obarray is to create it
  746.      empty and then add symbols to it one by one using `intern'.  Also,
  747.      you cannot intern a given symbol in more than one obarray.
  748.  
  749.      If the argument PREDICATE is non-`nil', then it must be a function
  750.      of one argument.  It is used to test each possible match, and the
  751.      match is accepted only if PREDICATE returns non-`nil'.  The
  752.      argument given to PREDICATE is either a cons cell from the alist
  753.      (the CAR of which is a string) or else it is a symbol (*not* a
  754.      symbol name) from the obarray.
  755.  
  756.      It is also possible to use a function symbol as COLLECTION.  Then
  757.      the function is solely responsible for performing completion;
  758.      `try-completion' returns whatever this function returns.  The
  759.      function is called with three arguments: STRING, PREDICATE and
  760.      `nil'.  (The reason for the third argument is so that the same
  761.      function can be used in `all-completions' and do the appropriate
  762.      thing in either case.)  *Note Programmed Completion::.
  763.  
  764.      In the first of the following examples, the string `foo' is
  765.      matched by three of the alist CARs.  All of the matches begin with
  766.      the characters `fooba', so that is the result.  In the second
  767.      example, there is only one possible match, and it is exact, so the
  768.      value is `t'.
  769.  
  770.           (try-completion
  771.            "foo"
  772.            '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
  773.                => "fooba"
  774.  
  775.           (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
  776.                => t
  777.  
  778.      In the following example, numerous symbols begin with the
  779.      characters `forw', and all of them begin with the word `forward'.
  780.      In most of the symbols, this is followed with a `-', but not in
  781.      all, so no more than `forward' can be completed.
  782.  
  783.           (try-completion "forw" obarray)
  784.                => "forward"
  785.  
  786.      Finally, in the following example, only two of the three possible
  787.      matches pass the predicate `test' (the string `foobaz' is too
  788.      short).  Both of those begin with the string `foobar'.
  789.  
  790.           (defun test (s)
  791.             (> (length (car s)) 6))
  792.                => test
  793.  
  794.           (try-completion
  795.            "foo"
  796.            '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
  797.                'test)
  798.                => "foobar"
  799.  
  800.  - Function: all-completions STRING COLLECTION &optional PREDICATE
  801.      This function returns a list of all possible completions, instead
  802.      of the longest substring they share.  The parameters to this
  803.      function are the same as to `try-completion'.
  804.  
  805.      If COLLECTION is a function, it is called with three arguments:
  806.      STRING, PREDICATE and `t', and `all-completions' returns whatever
  807.      the function returns.  *Note Programmed Completion::.
  808.  
  809.      Here is an example, using the function `test' shown in the example
  810.      for `try-completion':
  811.  
  812.           (defun test (s)
  813.             (> (length (car s)) 6))
  814.                => test
  815.  
  816.           (all-completions
  817.            "foo"
  818.            '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
  819.            (function test))
  820.                => ("foobar1" "foobar2")
  821.  
  822.  - Variable: completion-ignore-case
  823.      If the value of this variable is non-`nil', Emacs does not
  824.      consider case significant in completion.
  825.  
  826.    The two functions `try-completion' and `all-completions' have
  827. nothing in themselves to do with minibuffers.  However, completion is
  828. most often used there, which is why it is described in this chapter.
  829.  
  830. 
  831. File: elisp,  Node: Programmed Completion,  Next: Minibuffer Completion,  Prev: Basic Completion,  Up: Completion
  832.  
  833. Programmed Completion
  834. ---------------------
  835.  
  836.    Sometimes it is not possible to create an alist or an obarray
  837. containing all the intended possible completions.  In such a case, you
  838. can supply your own function to compute the completion of a given
  839. string.  This is called "programmed completion".
  840.  
  841.    To use this feature, pass a symbol with a function definition as the
  842. COLLECTION argument to `completing-read'.  This command arranges to
  843. pass the function along to `try-completion' and `all-completions',
  844. which will then let your function do all the work.
  845.  
  846.    The completion function should accept three arguments:
  847.  
  848.    * The string to be completed.
  849.  
  850.    * The predicate function to filter possible matches, or `nil' if
  851.      none.  Your function should call the predicate for each possible
  852.      match and ignore the possible match if the predicate returns `nil'.
  853.  
  854.    * A flag specifying the type of operation.
  855.  
  856.    There are three flag values for three operations:
  857.  
  858.    * `nil' specifies `try-completion'.  The completion function should
  859.      return the completion of the specified string, or `t' if the
  860.      string is an exact match already, or `nil' if the string matches no
  861.      possibility.
  862.  
  863.    * `t' specifies `all-completions'.  The completion function should
  864.      return a list of all possible completions of the specified string.
  865.  
  866.    * `lambda' specifies a test for an exact match.  The completion
  867.      function should return `t' if the specified string is an exact
  868.      match for some possibility; `nil' otherwise.
  869.  
  870.    It would be consistent and clean for completion functions to allow
  871. lambda expressions (lists which are functions) as well as function
  872. symbols as COLLECTION, but this is impossible.  Lists as completion
  873. tables are already assigned another meaning--as alists.  It would be
  874. unreliable to fail to handle an alist normally because it is also a
  875. possible function.  So you must arrange for any function you wish to
  876. use for completion to be encapsulated in a symbol.
  877.  
  878.    Emacs uses programmed completion when completing file names.  *Note
  879. File Name Completion::.
  880.  
  881. 
  882. File: elisp,  Node: Minibuffer Completion,  Next: Completion Commands,  Prev: Programmed Completion,  Up: Completion
  883.  
  884. Completion and the Minibuffer
  885. -----------------------------
  886.  
  887.    This section describes the basic interface for reading from the
  888. minibuffer with completion.
  889.  
  890.  - Function: completing-read PROMPT COLLECTION &optional PREDICATE
  891.           REQUIRE-MATCH INITIAL HIST
  892.      This function reads a string in the minibuffer, assisting the user
  893.      by providing completion.  It activates the minibuffer with prompt
  894.      PROMPT, which must be a string.  If INITIAL is non-`nil',
  895.      `completing-read' inserts it into the minibuffer as part of the
  896.      input.  Then it allows the user to edit the input, providing
  897.      several commands to attempt completion.
  898.  
  899.      The actual completion is done by passing COLLECTION and PREDICATE
  900.      to the function `try-completion'.  This happens in certain
  901.      commands bound in the local keymaps used for completion.
  902.  
  903.      If REQUIRE-MATCH is `t', the user is not allowed to exit unless
  904.      the input completes to an element of COLLECTION.  If REQUIRE-MATCH
  905.      is neither `nil' nor `t', then `completing-read' does not exit
  906.      unless the input typed is itself an element of COLLECTION.  To
  907.      accomplish this, `completing-read' calls `read-minibuffer'.  It
  908.      uses the value of `minibuffer-local-completion-map' as the keymap
  909.      if REQUIRE-MATCH is `nil', and uses
  910.      `minibuffer-local-must-match-map' if REQUIRE-MATCH is non-`nil'.
  911.  
  912.      The argument HIST specifies which history list variable to use for
  913.      saving the input and for minibuffer history commands.  It defaults
  914.      to `minibuffer-history'.  *Note Minibuffer History::.
  915.  
  916.      Case is ignored when comparing the input against the possible
  917.      matches if the built-in variable `completion-ignore-case' is
  918.      non-`nil'.  *Note Basic Completion::.
  919.  
  920.      For example:
  921.  
  922.           (completing-read
  923.            "Complete a foo: "
  924.            '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
  925.            nil t "fo")
  926.  
  927.           ;; After evaluating the preceding expression,
  928.           ;;   the following appears in the minibuffer:
  929.           
  930.           ---------- Buffer: Minibuffer ----------
  931.           Complete a foo: fo-!-
  932.           ---------- Buffer: Minibuffer ----------
  933.  
  934.      If the user then types `DEL DEL b RET', `completing-read' returns
  935.      `barfoo'.
  936.  
  937.      The `completing-read' function binds three variables to pass
  938.      information to the commands which actually do completion.  Here
  939.      they are:
  940.  
  941.     `minibuffer-completion-table'
  942.           This variable is bound to the COLLECTION argument.  It is
  943.           passed to the `try-completion' function.
  944.  
  945.     `minibuffer-completion-predicate'
  946.           This variable is bound to the PREDICATE argument.  It is
  947.           passed to the `try-completion' function.
  948.  
  949.     `minibuffer-completion-confirm'
  950.           This variable is bound to the REQUIRE-MATCH argument.  It is
  951.           used in the `minibuffer-complete-and-exit' function.
  952.  
  953. 
  954. File: elisp,  Node: Completion Commands,  Next: High-Level Completion,  Prev: Minibuffer Completion,  Up: Completion
  955.  
  956. Minibuffer Commands That Do Completion
  957. --------------------------------------
  958.  
  959.    This section describes the keymaps, commands and user options used in
  960. the minibuffer to do completion.
  961.  
  962.  - Variable: minibuffer-local-completion-map
  963.      `completing-read' uses this value as the local keymap when an
  964.      exact match of one of the completions is not required.  By
  965.      default, this keymap makes the following bindings:
  966.  
  967.     `?'
  968.           `minibuffer-completion-help'
  969.  
  970.     SPC
  971.           `minibuffer-complete-word'
  972.  
  973.     TAB
  974.           `minibuffer-complete'
  975.  
  976.      with other characters bound as in `minibuffer-local-map'.
  977.  
  978.  - Variable: minibuffer-local-must-match-map
  979.      `completing-read' uses this value as the local keymap when an
  980.      exact match of one of the completions is required.  Therefore, no
  981.      keys are bound to `exit-minibuffer', the command which exits the
  982.      minibuffer unconditionally.  By default, this keymap makes the
  983.      following bindings:
  984.  
  985.     `?'
  986.           `minibuffer-completion-help'
  987.  
  988.     SPC
  989.           `minibuffer-complete-word'
  990.  
  991.     TAB
  992.           `minibuffer-complete'
  993.  
  994.     LFD
  995.           `minibuffer-complete-and-exit'
  996.  
  997.     RET
  998.           `minibuffer-complete-and-exit'
  999.  
  1000.      with other characters bound as in `minibuffer-local-map'.
  1001.  
  1002.  - Variable: minibuffer-completion-table
  1003.      The value of this variable is the alist or obarray used for
  1004.      completion in the minibuffer.  This is the global variable that
  1005.      contains what `completing-read' passes to `try-completion'.  It is
  1006.      used by all the minibuffer completion functions, such as
  1007.      `minibuffer-complete-word'.
  1008.  
  1009.  - Variable: minibuffer-completion-predicate
  1010.      This variable's value is the predicate that `completing-read'
  1011.      passes to `try-completion'.  The variable is also used by the other
  1012.      minibuffer completion functions.
  1013.  
  1014.  - Command: minibuffer-complete-word
  1015.      This function completes the minibuffer contents by at most a single
  1016.      word.  Even if the minibuffer contents have only one completion,
  1017.      `minibuffer-complete-word' does not add any characters beyond the
  1018.      first character that is not a word constituent.  *Note Syntax
  1019.      Tables::.
  1020.  
  1021.  - Command: minibuffer-complete
  1022.      This function completes the minibuffer contents as far as possible.
  1023.  
  1024.  - Command: minibuffer-complete-and-exit
  1025.      This function completes the minibuffer contents, and exits if
  1026.      confirmation is not required, i.e., if
  1027.      `minibuffer-completion-confirm' is non-`nil'.  If confirmation
  1028.      *is* required, it is given by repeating this command immediately.
  1029.  
  1030.  - Variable: minibuffer-completion-confirm
  1031.      When the value of this variable is non-`nil', Emacs asks for
  1032.      confirmation of a completion before exiting the minibuffer.  The
  1033.      function `minibuffer-complete-and-exit' checks the value of this
  1034.      variable before it exits.
  1035.  
  1036.  - Command: minibuffer-completion-help
  1037.      This function creates a list of the possible completions of the
  1038.      current minibuffer contents.  It works by calling `all-completions'
  1039.      using the value of the variable `minibuffer-completion-table' as
  1040.      the COLLECTION argument, and the value of
  1041.      `minibuffer-completion-predicate' as the PREDICATE argument.  The
  1042.      list of completions is displayed as text in a buffer named
  1043.      `*Completions*'.
  1044.  
  1045.  - Function: display-completion-list COMPLETIONS
  1046.      This function displays COMPLETIONS to the stream in
  1047.      `standard-output', usually a buffer.  (*Note Streams::, for more
  1048.      information about streams.)  The argument COMPLETIONS is normally
  1049.      a list of completions just returned by `all-completions', but it
  1050.      does not have to be.  Each element may be a symbol or a string,
  1051.      either of which is simply printed, or a list of two strings, which
  1052.      is printed as if the strings were concatenated.
  1053.  
  1054.      This function is called by `minibuffer-completion-help'.  The most
  1055.      common way to use it is together with
  1056.      `with-output-to-temp-buffer', like this:
  1057.  
  1058.           (with-output-to-temp-buffer " *Completions*"
  1059.             (display-completion-list
  1060.               (all-completions (buffer-string) my-alist)))
  1061.  
  1062.  - User Option: completion-auto-help
  1063.      If this variable is non-`nil', the completion commands
  1064.      automatically display a list of possible completions whenever
  1065.      nothing can be completed because the next character is not
  1066.      uniquely determined.
  1067.  
  1068. 
  1069. File: elisp,  Node: High-Level Completion,  Next: Reading File Names,  Prev: Completion Commands,  Up: Completion
  1070.  
  1071. High-Level Completion  Functions
  1072. --------------------------------
  1073.  
  1074.    This section describes the higher-level convenient functions for
  1075. reading certain sorts of names with completion.
  1076.  
  1077.  - Function: read-buffer PROMPT &optional DEFAULT EXISTING
  1078.      This function reads the name of a buffer and returns it as a
  1079.      string.  The argument DEFAULT is the default name to use, the
  1080.      value to return if the user exits with an empty minibuffer.  If
  1081.      non-`nil', it should be a string.  It is mentioned in the prompt,
  1082.      but is not inserted in the minibuffer as initial input.
  1083.  
  1084.      If EXISTING is non-`nil', then the name specified must be that of
  1085.      an  existing buffer.  The usual commands to exit the minibuffer do
  1086.      not exit if the text is not valid, and RET does completion to
  1087.      attempt to find a valid name.  (However, DEFAULT is not checked
  1088.      for this; it is returned, whatever it is, if the user exits with
  1089.      the minibuffer empty.)
  1090.  
  1091.      In the following example, the user enters `minibuffer.t', and then
  1092.      types RET.  The argument EXISTING is `t', and the only buffer name
  1093.      starting with the given input is `minibuffer.texi', so that name
  1094.      is the value.
  1095.  
  1096.           (read-buffer "Buffer name? " "foo" t)
  1097.           ;; After evaluating the preceding expression,
  1098.           ;;   the following prompt appears,
  1099.           ;;   with an empty minibuffer:
  1100.  
  1101.           ---------- Buffer: Minibuffer ----------
  1102.           Buffer name? (default foo) -!-
  1103.           ---------- Buffer: Minibuffer ----------
  1104.  
  1105.           ;; The user types `minibuffer.t RET'.
  1106.           
  1107.                => "minibuffer.texi"
  1108.  
  1109.  - Function: read-command PROMPT
  1110.      This function reads the name of a command and returns it as a Lisp
  1111.      symbol.  The argument PROMPT is used as in `read-from-minibuffer'.
  1112.      Recall that a command is anything for which `commandp' returns
  1113.      `t', and a command name is a symbol for which `commandp' returns
  1114.      `t'.  *Note Interactive Call::.
  1115.  
  1116.           (read-command "Command name? ")
  1117.           ;; After evaluating the preceding expression,
  1118.           ;;   the following appears in the minibuffer:
  1119.  
  1120.           ---------- Buffer: Minibuffer ----------
  1121.           Command name?
  1122.           ---------- Buffer: Minibuffer ----------
  1123.  
  1124.      If the user types `forward-c RET', then this function returns
  1125.      `forward-char'.
  1126.  
  1127.      The `read-command' function is a simplified interface to the
  1128.      `completing-read' function.  It uses the `commandp' predicate to
  1129.      allow only commands to be entered, and it uses the variable
  1130.      `obarray' so as to be able to complete all extant Lisp symbols:
  1131.  
  1132.           (read-command PROMPT)
  1133.           ==
  1134.           (intern (completing-read PROMPT obarray 'commandp t nil))
  1135.  
  1136.  - Function: read-variable PROMPT
  1137.      This function reads the name of a user variable and returns it as a
  1138.      symbol.
  1139.  
  1140.           (read-variable "Variable name? ")
  1141.           
  1142.           ;; After evaluating the preceding expression,
  1143.           ;;   the following prompt appears,
  1144.           ;;   with an empty minibuffer:
  1145.  
  1146.           ---------- Buffer: Minibuffer ----------
  1147.           Variable name? -!-
  1148.           ---------- Buffer: Minibuffer ----------
  1149.  
  1150.      If the user then types `fill-p RET', `read-variable' will return
  1151.      `fill-prefix'.
  1152.  
  1153.      This function is similar to `read-command', but uses the predicate
  1154.      `user-variable-p' instead of `commandp':
  1155.  
  1156.           (read-variable PROMPT)
  1157.           ==
  1158.           (intern
  1159.            (completing-read PROMPT obarray 'user-variable-p t nil))
  1160.  
  1161. 
  1162. File: elisp,  Node: Reading File Names,  Next: Lisp Symbol Completion,  Prev: High-Level Completion,  Up: Completion
  1163.  
  1164. Reading File Names
  1165. ------------------
  1166.  
  1167.    Here is another high-level completion function, designed for reading
  1168. a file name.  It provides special features including automatic insertion
  1169. of the default directory.
  1170.  
  1171.  - Function: read-file-name PROMPT &optional DIRECTORY DEFAULT EXISTING
  1172.           INITIAL
  1173.      This function reads a file name in the minibuffer, prompting with
  1174.      PROMPT and providing completion.  If DEFAULT is non-`nil', then
  1175.      the function returns DEFAULT if the user just types RET.
  1176.  
  1177.      If EXISTING is non-`nil', then the name must refer to an existing
  1178.      file; then RET performs completion to make the name valid if
  1179.      possible, and then refuses to exit if it is not valid.  If the
  1180.      value of EXISTING is neither `nil' nor `t', then RET also requires
  1181.      confirmation after completion.
  1182.  
  1183.      The argument DIRECTORY specifies the directory to use for
  1184.      completion of relative file names.  Usually it is inserted in the
  1185.      minibuffer as initial input as well.  It defaults to the current
  1186.      buffer's default directory.
  1187.  
  1188.      If you specify INITIAL, that is an initial file name to insert in
  1189.      the buffer along with DIRECTORY.  In this case, point goes after
  1190.      DIRECTORY, before INITIAL.  The default for INITIAL is
  1191.      `nil'--don't insert any file name.  To see what INITIAL does, try
  1192.      the command `C-x C-v'.
  1193.  
  1194.      Here is an example:
  1195.  
  1196.           (read-file-name "The file is ")
  1197.           
  1198.           ;; After evaluating the preceding expression,
  1199.           ;;   the following appears in the minibuffer:
  1200.  
  1201.           ---------- Buffer: Minibuffer ----------
  1202.           The file is /gp/gnu/elisp/-!-
  1203.           ---------- Buffer: Minibuffer ----------
  1204.  
  1205.      Typing `manual TAB' results in the following:
  1206.  
  1207.           ---------- Buffer: Minibuffer ----------
  1208.           The file is /gp/gnu/elisp/manual.texi-!-
  1209.           ---------- Buffer: Minibuffer ----------
  1210.  
  1211.      If the user types RET, `read-file-name' returns the string
  1212.      `"/gp/gnu/elisp/manual.texi"'.
  1213.  
  1214.  - User Option: insert-default-directory
  1215.      This variable is used by `read-file-name'.  Its value controls
  1216.      whether `read-file-name' starts by placing the name of the default
  1217.      directory in the minibuffer, plus the initial file name if any.
  1218.      If the value of this variable is `nil', then `read-file-name' does
  1219.      not place any initial input in the minibuffer.  In that case, the
  1220.      default directory is still used for completion of relative file
  1221.      names, but is not displayed.
  1222.  
  1223.      For example:
  1224.  
  1225.           ;; Here the minibuffer starts out containing the default directory.
  1226.           
  1227.           (let ((insert-default-directory t))
  1228.             (read-file-name "The file is "))
  1229.  
  1230.           ---------- Buffer: Minibuffer ----------
  1231.           The file is ~lewis/manual/-!-
  1232.           ---------- Buffer: Minibuffer ----------
  1233.  
  1234.           ;; Here the minibuffer is empty and only the prompt
  1235.           ;;   appears on its line.
  1236.           
  1237.           (let ((insert-default-directory nil))
  1238.             (read-file-name "The file is "))
  1239.  
  1240.           ---------- Buffer: Minibuffer ----------
  1241.           The file is -!-
  1242.           ---------- Buffer: Minibuffer ----------
  1243.  
  1244. 
  1245. File: elisp,  Node: Lisp Symbol Completion,  Prev: Reading File Names,  Up: Completion
  1246.  
  1247. Lisp Symbol Completion
  1248. ----------------------
  1249.  
  1250.    If you type a part of a symbol, and then type `M-TAB'
  1251. (`lisp-complete-symbol'), this command attempts to fill in as much more
  1252. of the symbol name as it can.  Not only does this save typing, but it
  1253. can help you with the name of a symbol that you have partially
  1254. forgotten.
  1255.  
  1256.  - Command: lisp-complete-symbol
  1257.      This function performs completion on the symbol name preceding
  1258.      point.  The name is completed against the symbols in the global
  1259.      variable `obarray', and characters from the completion are
  1260.      inserted into the buffer, making the name longer.  If there is
  1261.      more than one completion, a list of all possible completions is
  1262.      placed in the `*Help*' buffer.  The bell rings if there is no
  1263.      possible completion in `obarray'.
  1264.  
  1265.      If an open parenthesis immediately precedes the name, only symbols
  1266.      with function definitions are considered.  (By reducing the number
  1267.      of alternatives, this may succeed in completing more characters.)
  1268.      Otherwise, symbols with either a function definition, a value, or
  1269.      at least one property are considered.
  1270.  
  1271.      `lisp-complete-symbol' returns `t' if the symbol had an exact, and
  1272.      unique, match; otherwise, it returns `nil'.
  1273.  
  1274.      In the following example, the user has already inserted `(forwa'
  1275.      into the buffer `foo.el'.  The command `lisp-complete-symbol' then
  1276.      completes the name to `(forward-'.
  1277.  
  1278.           ---------- Buffer: foo.el ----------
  1279.           (forwa-!-
  1280.           ---------- Buffer: foo.el ----------
  1281.  
  1282.           (lisp-complete-symbol)
  1283.                => nil
  1284.  
  1285.           ---------- Buffer: foo.el ----------
  1286.           (forward--!-
  1287.           ---------- Buffer: foo.el ----------
  1288.  
  1289.